/*
 * Copyright 2016-2021 the original author.All rights reserved.
 * Kingstar(honeysoft@126.com)
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.teasoft.bee.osql;

import java.util.List;
import java.util.Map;

import org.teasoft.bee.osql.interccept.InterceptorChain;

/**
 * 使用Map而非Javabean实体的数据库操作接口,默认不处理null和空字符串(与Suid,SuidRich风格兼容)
 * <br>Database operation interface using map instead of specific entity,
 * <br>the null and empty string are not handled by default.
 * Suid (select,update,insert,delete)
 * @author Kingstar
 * @since  1.9
 */
public interface MapSuid {

	/**
	 * 使用MapSql查询数据.Use MapSql to select data.
	 * @param mapSql MapSql instance
	 * @return List<String[]>结构的多行记录.
	 * <br>the multi-line record of List<String[]> structure.
	 */
	public List<String[]> selectString(MapSql mapSql);

	/**
	 * 使用MapSql查询数据.Use MapSql to select data.
	 * @param mapSql MapSql instance
	 * @return Json格式的多行记录.multi-line record in Json format.
	 */
	public String selectJson(MapSql mapSql);

	/**
	 * 使用MapSql查询数据.Use MapSql to select data.
	 * <br>one map element as : field-name:value
	 * @param mapSql MapSql instance
	 * @return List<Map<String, Object>>结构的多行记录.
	 * <br>the multi-line record of List<Map<String, Object>> structure.
	 */
	public List<Map<String, Object>> select(MapSql mapSql);

	/**
	 * 使用MapSql查询数据.Use MapSql to select data.
	 * <br>one map element as : fieldName:value
	 * @param mapSql MapSql instance
	 * @return 包装在一个Map中的一行数据.returns a row of data wrapped in a map.
	 */
	public Map<String, Object> selectOne(MapSql mapSql);
	
	/**
	 * 更新记录,并返回受影响的行数.Update the record and return the number of rows affected.
	 * @param mapSql MapSql instance
	 * MapSql的put方法用于SQL语句的where部分,putNew用于update类型SQL的set部分.
	 * MapSql' put method for SQL where part, putNew for update SQL 's set part.
	 * @return 成功更新的记录数,若失败则返回小于0的整数. the numbers of update records successfully,if fails, return integer less than 0. 
	 * @since 1.9.8
	 */
	public int update(MapSql mapSql);

	/**
	 * 插入并返回记录的id值.Insert and return the id value of the record.
	 * id值可由Bee自动生成分布式id.
	 * <br>注意:若id由DB生成,需考虑DB是否支持,且对应JDBC驱动要支持返回id.
	 * <br>The ID value can be generated automatically by bee
	 * <br>Note: if id is generated by DB, consider whether DB supports it,
	 * <br> and the corresponding JDBC driver supports returning id.
	 * @param mapSql MapSql instance
	 * @return 若成功,返回插入记录的id值;若失败则返回小于0的数.
	 * <br>If successful, return the id value of the inserted record; if fails, return number less than 0.
	 */
	public long insertAndReturnId(MapSql mapSql);
	
	/**
	 * 插入记录,并返回成功插入的记录数.Inserts record and returns the number of the record successfully inserted.
	 * @param mapSql MapSql instance
	 * @return 成功插入的记录数,若失败则返回小于0的整数.the numbers of insert records successfully,if fails, return integer less than 0.
	 */
	public int insert(MapSql mapSql);
	
	/**
	 * 使用MapSql删除记录.Use MapSql to delete record.
	 * @param mapSql MapSql instance
	 * @return 成功删除的记录数,若失败则返回小于0的整数. the numbers of delete records successfully,if fails, return integer less than 0. 
	 */
	public int delete(MapSql mapSql);
	
	/**
	 * 统计符合条件的记录数.count the number of qualified record.
	 * @param mapSql MapSql instance
	 * @return 符合条件的记录数,若失败则返回小于0的整数.the number of qualified record,if fails, return integer less than 0.
	 * @since 1.9.8
	 */
	public int count(MapSql mapSql);
	
	
	/**
	 * 设置数据源名称(对应数据源必须已定义)
	 * @param dsName dataSource name
	 */
	public void setDataSourceName(String dsName);

	public String getDataSourceName();
	
	/**
	 * 可用于某个生成的Suid对象,需要设置特定拦截器.
	 * @return InterceptorChain
	 */
	public InterceptorChain getInterceptorChain();
}
